Debugging

There are three versions of the Allegro library: the normal optimised code, one with extra debugging support, and a profiling version. See the platform specific readme files for information about how to install and link with these alternative libs. Although you will obviously want to use the optimised library for the final version of your program, it can be very useful to link with the debug lib while you are working on it, because this will make debugging much easier, and includes assert tests that will help to locate errors in your code at an earlier stage. Allegro also contains some debugging helper functions:


void ASSERT(condition);

Debugging helper macro. Normally compiles away to nothing, but if you defined the preprocessor symbol DEBUGMODE before including Allegro headers, it will check the supplied condition and call al_assert() if it fails, whose default action is to stop the program and report the assert. You can use this macro even when Allegro has not been initialised. Example: 
      #define DEBUGMODE
      #include 
      ...
      void my_blitter(BITMAP *source, int flags)
      {
         int some_variables;
         ASSERT(source != NULL);
         ASSERT(flags & GAME_RUNNING);
         ...
      }
See also: al_assert, TRACE, register_assert_handler.
Examples using this: expackf.
void TRACE(char *msg, ...);

Debugging helper macro. Normally compiles away to nothing, but if you defined the preprocessor symbol DEBUGMODE before including Allegro headers, it passes the supplied message given in ASCII format to al_trace(). Example: 
      #define DEBUGMODE
      #include 
      ...
      void my_blitter(BITMAP *source, int flags)
      {
         static int count_call = 0;
         TRACE("my_blitter() called %d times.\n", count_call++);
         ...
      }
See also: al_trace, ASSERT, register_trace_handler.
void register_assert_handler(int (*handler)(const char *msg));

Supplies a custom handler function for dealing with assert failures. Your callback will be passed a formatted error message in ASCII, and should return non-zero if it has processed the error, or zero to continue with the default actions. You could use this to ignore assert failures, or to display the error messages on a graphics mode screen without aborting the program. You can call this function even when Allegro has not been initialised. Example: 
   int show_but_continue(const char *text)
   {
       alert("Uh oh...", "Fasten your seat belts.", text,
             "&Go on!", NULL, 'g', 0);
       return 1;
   }
   ...
      register_assert(show_but_continue);
      ASSERT(0); /* This won't crash the program now. */
See also: al_assert, ASSERT, register_trace_handler.
void register_trace_handler(int (*handler)(const char *msg));

Supplies a custom handler function for dealing with trace output. Your callback will be passed a formatted error message in ASCII, and should return non-zero if it has processed the message, or zero to continue with the default actions. You could use this to ignore trace output, or to display the messages on a second monochrome monitor, etc. You can call this function even when Allegro has not been initialised. Example: 
   int network_broadcaster(const char *text)
   {
      int f;

      for (int f = 0; f < connected_clients; f++)
         send_msg_to_client(client[f], text);
         
      return 0; /* Let normal tracing occur. */
   }
   ...
      register_trace_handler(network_broadcaster);
      TRACE("Networked tracing activated\n");
See also: al_trace, TRACE, register_assert_handler.
void al_assert(const char *file, int line);

Raises an assert for an error at the specified file and line number. The file parameter is always given in ASCII format. By default, this will call the system driver's assert handler. If there is none, the error will be sent to stderr and the program will abort. However, if the environment variable ALLEGRO_ASSERT is set, this function writes a message into the file specified by the environment variable and program execution will continue. If none of this behaviours is wanted, you can override them with a custom assert handler.

You will usually want to use the ASSERT() macro instead of calling this function directly.

See also: ASSERT, al_trace, register_assert_handler.
void al_trace(const char *msg, ...);

Outputs a debugging trace message, using a printf() format string given in ASCII. If you have installed a custom trace handler it uses that, or if the environment variable ALLEGRO_TRACE is set it writes into the file specified by the environment, otherwise it writes the message to "allegro.log" in the current directory. You will usually want to use the TRACE() macro instead of calling this function directly.
See also: TRACE, al_assert, register_trace_handler.
Back to contents